AS v1.30 (SCLib build)


ChangeLog
=========


This is the changelog for this version of AS, which is based on AS v1.28 by
Niklas Rjemo (and Nick Burrett).

Contact <URL:mailto:ds@youmustbejoking.demon.co.uk> if you have comments,
ideas or bug reports.


-- 
Darren Salt


New command line options
========================

-target
	Sets the target ARM CPU. Defaults to ARM2.
	Target	Equivalents
	------	-----------
	ARM2
	ARM250
	ARM3
	ARM6
	ARM7
	ARM7M
	ARM8
	SA1	SA110, STRONGARM

-nolocal
	Disables the builtin LOCAL and enables $l and $L expansion.

-objasm
	Enables alternative interpretation of ''' and '\'. It also disables
	octal, allows "" within quotes, allows C-style escapes in " strings,
	and shifts the priority of the shift and rotate operators above that
	of + and binary -.

-upper
	Assembler mnemonics must be in upper case.

-D
	Predefines a (string) variable. Usage is "-Dfoo", "-D foo=bar". The
	space is optional.

-fussy
	Enables some extra informationals, eg. type & instruction
	conversions.


Changed command line options
----------------------------

-pedantic
	Enables some extra warnings and a few more informationals, eg.
	implicit imports.


Register names
--------------

If -gcc is specified on the command line, then the following
names may be used:
ARM	r0  r1  r2  r3  r4  r5  r6  r7  r8  r9  r10 r11 r12 r13 r14 r15
	a1  a2  a3  a4  v1  v2  v3  v4  v5  v6  sl  fp  ip  sp  lr  pc
					    rfp
FPA	f0  f1  f2  f3  f4  f5  f6  f7


Macros
------

Macros are defined using

	MACRO
$label	name	$arg1,$arg2...
	macro body
	MEND

and may have up to 16 arguments (including the label argument, if present).
These arguments are used in the same way as the $<label> constructs described
below, but are expanded before them (and thus may contain $<label> constructs
to be expanded). Macros are called as if they were normal assembler
mnemonics; trailing arguments and the label may be omitted.

Up to 10 macro calls may be nested.

Macros may not have the same names as any of the builtins; any that do simply
cannot be called.

$<label> constructs are expanded except when defining a macro, or when in
|...|, "..." or '...'. However, the builtin LOCAL support uses $L and $l case
insensitively, hence these are not expanded unless -nolocal was in the
command line. If it is necessary to separate the label from the following
text, it may be suffixed by '.'. (Note that AS allows label names to contain
dots; such labels may not be expanded unless enclosed in |...|.)

Macro names may be enclosed in |...|.


Mnemonics
---------

LFM, SFM
	Examples:
	LFM	f0,3,[a1],#36
	SFM	f4,1,[v1]
	LFM	f2,2,[v1,#12]
	LFM	f2,2,[v1,#24]!
	SFM	f1,1,wibble

	SFMFD	f4,4,[sp]!
	LFMIA	f4,2,[v3]

	Allowable stack types are DB, IA, EA, FD.

MRS, MSR
	CPSR/SPSR <-> register transfer.
	The 'new' suffixes (_c, _f etc.) are allowed.

LDR/STR to label (implied PC-relative)
	This should be used in preference to [pc,#<label>-.-8].

LDF, STF
	Now allow the = form for types single and double; attempts to use
	this with extended or packed are altered to use type double.

DCFS, DCFD
	Now accept int parameters.

LDRH, LDRSH, LDRSB
STRH, STRSH, STRSB
	Implemented. Warnings given about half-word forms. Cannot be used to
	refer to labels in other areas (linker can't handle these).

ADRL	Implemented. Will warn you if the second half of this instruction
	pair can be removed safely.
	[Warning disabled temporarily; linkers do cope with ADRL. I therefore
	need to restrict the warning to same-area ADRLs.]

NOP
	Equivalent to MOV r0,r0. May take a register parameter (R0..R14), in
	which case that register is used instead of R0.

STACK	<list>
	Generates an APCS function prologue, with options to stack the four
	argument registers, some or all of the register variables, and some
	or all of the fp register variables.

	<list> is a comma-separated of register 'classes', each with an
	optional number of registers to stack. The classes are:
		Class	Register type	No. stacked	First stacked
		a	Argument	0 to 4		a1
		v	Variable	0 to 6		v1
		f	FP variable	0 to 4		f4
	The syntax is:
		<class>		stack all in this class
		<class>=<n>	stack n registers in this class
	If a class is omitted, no registers in that class are stacked.
	Classes may not be repeated.

	The parameters are remembered until the next STACK, so that they can
	be used by RET and TAIL.

	Examples:
	STACK
			MOV	ip,sp
			STMFD	sp!,{fp,ip,lr,pc}
			SUB	fp,ip,#4
	STACK	v=3
			MOV	ip,sp
			STMFD	sp!,{v1-v3,fp,ip,lr,pc}
			SUB	fp,ip,#4
	STACK	a,f=3
			MOV	ip,sp
			STMFD	sp!,{a1-a4}
			STMFD	sp!,{fp,ip,lr,pc}
			SFM	f4,3,[sp,#-36]! ; stacks f4-f6
			SUB	fp,ip,#20	; note [fp,#4] == a1

RET
	Generates an APCS function epilogue using the parameters of the most
	recent STACK.

	Examples:
	STACK
	...
	RET
			LDMDB	fp,{fp,sp,pc}^
	STACK	v=3
	...
	RET
			LDMDB	fp,{v1-v3,fp,sp,pc}^
	STACK	a,f=3
	...
	RETEQ
			LFMEQ	f4,3,[sp],#36
			LDMEQDB	fp,{fp,sp,pc}^


TAIL
	Generates an APCS function-with-tail-call epilogue using the
	parameters of the most recent STACK.

	If the optional [soon to be mandatory] parameter (as for B and BL) is
	supplied, it also generates a branch instruction.

	Examples:
	STACK
	...
	TAIL
			LDMDB	fp,{fp,sp,lr}
	STACK	v=3
	...
	TAIL	printf
			LDMDB	fp,{v1-v3,fp,sp,lr}
			B	printf
	STACK	a,f=3
	...
	TAILEQ
			LFMEQ	f4,3,[sp],#36
			LDMEQDB	fp,{fp,sp,lr}


Directives
----------

HEAD
	Assembles a function name header for backtrace purposes, eg.
		HEAD	"Wibble"
	is equivalent to
		=	"Wibble",0
		ALIGN
		&	&FF000008

ALIGN, %
	These now zero fill.

^
	Allows the <base>,<register> form.
	(New internal datatype ValueAddr for this - see h.value)

	ValueAddr labels may be used in arithmetic as follows:
		ValueAddr + int
		ValueAddr - int
		ValueAddr - ValueAddr
	In the latter case, both offsets must be relative to the same
	register.

[
|
]
	Full arbitrarily-nested IFs are allowed.
	Be especially careful about mixing [ and WHILE - the assembler will
	not pick up WHILEs or WENDs whilst searching for | or ].

GBLA, GBLL, GBLS
LCLA, LCLL, LCLS
	Global and local variable declaration, for integer, boolean and
	string. Local variables may only be used within macros.
	Usage:		<decl>	<var>

SETA, SETL, SETS
	Set a variable of the specified type.
	Usage:	<var>	<set>	<expression>

LOCAL
	Implemented.
	Affects labels with suffix '$l' or '$L'.

WHILE, WEND
	Implemented.
	Be especially careful about mixing WHILE and [ - the assembler will
	not pick up [s, |s or ]s within the loop when the condition becomes
	false.
	Constant expressions are not allowed.

ASSERT	Implemented, in the usual way.


** Illegal uses:

WHILE loops and IF blocks must be contained entirely within a macro or a
file. It is permitted to use GET within any of these constructs.

As a consequence of the above, END and LNK may not be used within WHILE
loops or macros; END may not be used within IF blocks.

LNK, however, may be used within an IF block, provided that it is not nested
within another IF block in the current file.

MEND is unrecognised unless a macro is being defined. It does not form part
of the macro definition.


Labels
------

Labels beginning "Label$$"
	Reserved for internal use. Such labels may not be exported.

Routine labels, and references %fN, %bN, %N
	Implemented, except for %N. (N represents the label number.)

Local labels
	Implemented. These labels use the reserved names.

{TRUE}, {FALSE}
	Implemented as boolean values.

{PC}
	Synonym for '.'.

. in label names
	Deprecated. You are encouraged to use the |...| form for such labels.


Operators
---------

:INDEX:
	For use with labels declared using the allocation directive #.
	This unary operator converts the label to an int value.

:LEFT:, :RIGHT:, :LEN:, :STR:
	The usual string operators. (BASIC's MID$ may be emulated by using
	"<string>:RIGHT:x:LEFT:y".)

:CC:	Alternative to + for strings

:CHR:	CHR$ n. :CHR:0 is currently unuseable...

:DEF:	:DEF:foo returns {TRUE} if foo has been declared earlier in this
	translation unit, or is a predefined symbol.

?	Recognised; not implemented.
	(Size of the assembled object on the same source line as the label.)

=, <>	Alternatives to == and !=.


Error reporting
---------------

Errors are reported in the form:
	Error: Something at line 20 in macro Wibble in file 's.File'
	  at line 12 in macro Flip
	  at line 45

Throwback is done similarly, eg.

	Errors in file:  s.File

	    Line  Type		Description
	      20  Error		Something

	Errors in file:  s.Source

	    Line  Type		Description
	      12  Error		  called from here in macro Flip
	      45  Error		  called from here

Errors in included files are similarly traced.


Problems
--------

$ expansion is problematic - it really needs a rewrite of input.c.

There /may/ be Prefix$Dir/Throwback problems...
